The |BSelect Record|B icon opens a dBASE III compatible database and selects one or more records using key fields.
Before selecting records using one or more of the key fields in the database, you must define a set of variables containing the values you wish to specify as the key fields. You can define variables using either the |BModule|B, |BSubroutine|B or |BVariable|B icons.
Using the |BSelect Record|B icon, first enter the database filename. This will open the database and display all the fields highlighting the key fields with a |H>|H character. You can double-click on the key fields and a list of variables will be presented for you to link variables to key fields for searching the database.
If you want to restrict the search to just what is entered, then you must terminate your variable value with the '|' (vertical bar) character. This will ignore all records that do not exactly match. These values are case sensitive.
The |BSelect Record|B icon can be a parent to the other database icons which perform the read and write operations. As a parent the |BSelect Record|B icon acts like a loop in that the actions of its children are performed repeatedly until all the selected records have been processed.
If you do not link any variables to key fields, the |BSelect Record|B icon selects the very first record in your data file. As a parent it then loops through all the data records sequentially. If the |BSelect Record|B icon is not a parent then it selects only the first record for use by its siblings.
Note that you may have as many as ten separate database files open for selection in your application. Each of the database files requires a separate |BSelect Record|B icon. This is useful in a case where you have stored the names and addresses in one file and the test scores or other vital statistics in another file. By using two separate |BSelect Record|B icons, you can select and read information from both files.
Click on the |HDirectory|H gadget to select a database through the file requester, or type the database name in the filename field and press the |HReturn|H key.
The specified file's fields are shown in the window with the key fields marked by the |H>|H character. Clicking on the field name in the list presents a list of variables that have been defined in the flow. Select a variable from the list to link it to a field. Repeat this procedure for each of the fields you want to link to a variable. Be sure that the variables you are using have been assigned values prior to the |BSelect Record|B icon. When the |BSelect Record|B icon executes, it first locates one or more records using the specified key fields and then uses the non-key fields, if any, to locate the record precisely.
If a key field is assigned a variable, the interpretation is to select all the records that match that variable. If no fields are assigned to variables, all records are selected starting from the first one.
If more than one key field is linked to variables, the interpretation is to select all the records that match the variable in key field 1 and the variable in key field 2 and the variable in key field 3 and so on. You may also use non-key fields in addition to the key fields to select records.
If the |BSelect Record|B icon fails to find a single record in the database that matches the specified keys, then it does not perform the actions of its children and the application moves to the next icon. If you want to perform specific actions such as adding a new record, then you must use variables to determine if the |BSelect Record|B icon failed to locate a record.
|02 Read/Write Record
The |BRead/Write Record|B icon is the primary method for reading and updating information in a single record in the database. It is also used to add new records to the database.
Specify the name of the database file to be used in the |HFilename|H field. Be sure that the database file you have specified has been opened previously by a |BSelect Record|B icon. If you do not have a |BSelect Record|B icon defined, then your |BRead/Write|B icon will fail to do anything.
Click on the multistate gadget to select one of three operations: |HRead|H, |HInsert|H or |HUpdate|H a record. |HRead|H is used for reading the data fields in the currently selected record into the variables that have been linked.
|HInsert|H adds new records to the database. You can use it, for instance, if the |BSelect Record|B operation fails to find a record with key fields matching key values specified.
If the operation is an |HUpdate|H, the action updates the values in the specified fields of the currently selected record.
A list of the available fields is shown in the window. Double-clicking on the field name in the list presents a list of previously defined variables. You can select variables from this list and link them to the fields. The linking operation is identical to that in the |BSelect Record|B icon. It is a good practice to use different variables for record selection and for record reading/writing. For instance, you may want to use multiple |BRead/Write|B icons for reading the same record into different variables in your application.
|03 Delete
Use the |BDelete|B icon to remove a record from the database. Records to be deleted must first be selected with the |BSelect Record|B icon.
Specify the name of the database file to be used in the |HFilename|H field.
Once the |BSelect Record|B icon has selected a record, the |BDelete|B icon will remove it from the specified database.
|04 Variables
You use the |BVariables|B icon to define variables by assigning values or expressions to them.
In |IAmigaVision|I, variables can be created using a |BModule|B icon, a |BSubroutine|B icon or the |BVariables|B icon. Variables created by |BModule|B and |BSubroutine|B icons are called "local". For instance, a variable defined in a |BModule|B icon will be useful only within that |BModule|B. Similarly a variable defined in a |BSubroutine|B icon has validity only within that |BSubroutine|B.
The |BVariables|B icon, in contrast, can create variables that can be used throughout an application. Thus they are called "global" variables. In addition to creating global variables, the |BVariables|B icon can also be used for modifying the values of all variables (global and local).
In general, if you use variables that have not been previously defined, new global variables will be created.
The |HDelete|H, |HInsert|H and |HMove|H gadgets are used to arrange expressions in the Expressions (or variable definitions) Window. When you click on |HInsert|H, the |BExpression Editor|B is presented and you may define a number of variables. When you exit the |BExpression Editor|B by clicking on the |HOK|H gadget, the variables along with their defining expressions will appear in the Expressions window.
To insert expressions in a particular place in the list of existing expressions in the window, click on the expression above the line where you wish to insert the new expression. When the expression is highlighted, click on the |HInsert|H gadget.
To delete an expression from the list, click on the expression in the window. Then click on the |HDelete|H gadget.
To move an expression elsewhere in the list, click on the expression. Click on the |HMove|H gadget. To move a variable definition above its original position, click on the definition above the line where you want to move. To move a variable definition below its original position, click on the definition below the line where you want to move.
Double-clicking on a variable definition presents it in the |BExpression Editor|B for editing.
|05 Output
You may use the |BOutput|B icon to produce a line of formatted output of text or values of variables in your application. The output can be sent either to a file or to a printer. If the output is sent to a file it is saved in the ASCII format.
Note that the |BOutput|B icon allows you to format only a single line of output that has a maximum of 132 characters. If you need multiple lines (for example, to include headings in a report), you must use one |BOutput|B icon for each line.
Click on the multistate gadget to specify the output destination: |HPrinter|H or |HFile|H. If you select the |HFile|H option then an ASCII file is created using the specified filename. Specify the name of the output file to be used in the |HFilename|H field. If a file by that name already exists, the output is simply appended to the end of the existing file.
When you click on the |HVar|H gadget the variable list is presented. When you select a variable from the list, it will appear in the |HVar|H field. When the |BOutput|B icon is executed the value of this variable will be printed at the column location that you specify.
You have the option of specifying a text string instead of a variable. Click on the |HText|H field to type in a literal string of text to be output. This is useful for specifying a title, column heading or other fixed textual information on the line to be printed.
After specifying a variable or a text string to be output you have to click on the |HColumn|H gadget to enter the starting column number for printing. The maximum number of columns is 132. You should carefully plan the output so that string variables such as names have adequate space. Thus you have to allocate all the variable values you want shown in a single line over the limited space of 132 columns.
Click on the |HInsert|H gadget to add the specification to the output format window. This window shows the starting column location; a code letter (T or V) indicating whether at that location a text string or a variable value is being printed; and either the name of the variable or the text string.
The |HDelete|H, |HInsert|H and |HMove|H gadgets are used to arrange the output format items in the window on the left. The order of items in the list does not matter, as the printing occurs according to the specified column location.
To insert a new item at a particular place in the list in the window, click on the item above the line where you wish to insert the new expression. When the item is highlighted, click on the |HInsert|H gadget.
To delete an item from the list, click on the item and then click on the |HDelete|H gadget.
To move an item elsewhere in the list, click on the item and then click on the |HMove|H gadget. To place the item above its original position, click on the item above the line where you want the expression to move. To place the item below its original position, click on the item below the line where you want the expression to move.
Double-clicking on an item presents it for modification in the |HVar|H (or |HText|H) and the |HColumn|H fields. After modification you must insert it again using the |HInsert|H gadget and then use the |HDelete|H gadget to delete the original item.
|06 Data Form
You use the |BData Form|B icon to create forms on the screen for data entry. A data entry form is a screen which contains data fields into which the user types information. The data fields for the form are created in the |BObject Editor|B by using the Objects-Add menu to create an Input Field.
In addition to data fields, the form may include hit boxes for entering non-field responses. As an example, the form might include hit boxes for OK and CANCEL, which could be used to exit the form.
You can validate the data entered by the user in a form by checking each field. The |BObject Editor|B lets you specify validation expressions and error messages for each field. Alternatively, you may validate the data entered in all the fields after the user exits the form. You may also specify response strings for exiting and/or aborting a form.
Click on the |HObject Editor|H gadget to enter the object editor. In the |BObject Editor|B you define the screen appearance and all the data fields for the form. For each of the data fields you must specify a variable. The data entered by the user in this field is assigned to that variable.
In the |BObject Editor|B you can also specify hit boxes for exiting or aborting the form.
Click on the multistate gadget to specify whether input should be validated for each field or when the form is exited. If you choose |HValidate Fields|H, the exit condition for each field is checked as the data for the field is entered. If you select |HValidate on Exit|H, field entries are not validated until the form is exited.
Note that if you select |HValidate on Exit|H, you must specify a string in the |HExit On|H field for the form. This string must match the response string you specified for the hit box when you created the data form in the |BObject Editor|B. Similarly, if you want to provide the user an abort option in the data form, you must specify a hit box with a response string. This same string must then be entered in the |HForm|H requester in the field for the |HAbort On|H string.
A form is usually exited when the user clicks on the hit box with the response string specified next to |HExit On|H. The values of variables that are linked to the data fields are then modified and saved. However, if the |HAbort|H condition occurs, variables are reset to their values prior to the |BData Form|B icon.
Click in the |HExit On|H field and type in the string which will cause the form to be exited. Click in the |HAbort On|H field and type in the string which will cause the form to be aborted.
|07 Form Exit
You use the |BForm Exit|B icon to exit from a data form without the use of a hit box. The |BForm Exit|B icon is not required for each |BData Form|B icon. Normally, a |BData Form|B icon is exited when either the |HExit On|H string or the |HAbort On|H string is encountered. You may, however, include hit boxes for other response strings on the form. You might then check for one these other response strings and conditionally execute other icons. The |BForm Exit|B icon could then be used to exit the |BData Form|B icon.
Using the multistate gadget, you may specify the mode as either |HExit|H or |HAbort|H. If you specify |HExit|H, the variable values adjusted by the data fields in the form are modified and saved. If you choose |HAbort|H, variable values are reset to their values prior to the |BData Form|B icon.
